<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Design Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->


<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


<!-- ****************** NavBar ****************** -->
<div id="menubar">
	<div class="banner">
        <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
    </div>
<ul>
  <li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
      .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
    </style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Design Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#notation">1.1. Notation</a></li>
<li><a href="introduction.html#sec:IDE_Overview">1.2. IDE Components</a>
<ul class="sectlevel3">
<li><a href="introduction.html#sec:Naming_Conventions">1.2.1. Naming Conventions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="eclipse_setup.html#_eclipse-setup">2. Eclipse Setup</a>
<ul class="sectlevel2">
<li><a href="eclipse_setup.html#_system-requirements">2.1. System Requirements</a></li>
<li><a href="eclipse_setup.html#_contribute">2.2. Contribute</a>
<ul class="sectlevel3">
<li><a href="eclipse_setup.html#_eclipse-installer">2.2.1. Eclipse Installer</a>
<ul class="sectlevel4">
<li><a href="eclipse_setup.html#_changing-the-setup-script">2.2.1.1. Changing the Setup Script</a></li>
</ul>
</li>
<li><a href="eclipse_setup.html#_manual-ide-configuration">2.2.2. Manual IDE Configuration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="release_engineering.html#_release-engineering">3. Release Engineering</a>
<ul class="sectlevel2">
<li><a href="release_engineering.html#_nightly-build-on-eclipse-infrastructure">3.1. Nightly build on Eclipse infrastructure</a></li>
<li><a href="release_engineering.html#_build-the-n4js-ide-from-command-line">3.2. Build the N4JS IDE from command line</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_publish-maven-tooling-code-org-eclipse-n4js-releng-util-code">3.2.1. Publish maven-tooling <code>org.eclipse.n4js.releng.util</code></a></li>
<li><a href="release_engineering.html#sec:test-verdaccio">3.2.2. Test Verdaccio containing n4js-libs</a></li>
<li><a href="release_engineering.html#_generation-of-eclipse-help-for-spec-and-design-document">3.2.3. Generation of Eclipse help for spec and design document</a></li>
</ul>
</li>
<li><a href="release_engineering.html#_updating-frameworks-and-dependencies">3.3. Updating frameworks and dependencies</a>
<ul class="sectlevel3">
<li><a href="release_engineering.html#_update-of-eclipse-emf-xtext-etc">3.3.1. Update of Eclipse, EMF, Xtext, etc.</a></li>
<li><a href="release_engineering.html#_update-of-the-embedded-jre">3.3.2. Update of the embedded JRE</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tips_and_tricks.html#_tips-and-tricks">4. Tips and Tricks</a>
<ul class="sectlevel2">
<li><a href="tips_and_tricks.html#_naming">4.1. Naming</a></li>
<li><a href="tips_and_tricks.html#_logging">4.2. Logging</a></li>
<li><a href="tips_and_tricks.html#_cancellation-handling">4.3. Cancellation Handling</a></li>
<li><a href="tips_and_tricks.html#_caching">4.4. Caching</a></li>
<li><a href="tips_and_tricks.html#_dependency-injection">4.5. Dependency Injection</a></li>
<li><a href="tips_and_tricks.html#_miscellaneous">4.6. Miscellaneous</a></li>
</ul>
</li>
<li><a href="parser.html#_parser">5. Parser</a>
<ul class="sectlevel2">
<li><a href="parser.html#sec:Parser_Overview">5.1. Overview</a></li>
<li><a href="parser.html#sec:N4JS_Parser">5.2. N4JS Parser</a></li>
<li><a href="parser.html#sec:Parser_Generation_Post_Processing">5.3. Parser Generation Post-Processing</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Automatic_Semicolon_Insertion">5.3.1. Automatic Semicolon Insertion</a>
<ul class="sectlevel4">
<li><a href="parser.html#sec:Injected_code_in_the_Antlr_grammar_file">5.3.1.1. Injected code in the Antlr grammar file</a></li>
<li><a href="parser.html#sec:Customized_error_recovery">5.3.1.2. Customized error recovery</a></li>
</ul>
</li>
<li><a href="parser.html#sec:_No_line_terminator_allowed_here__handling">5.3.2. Async and <code>No line terminator allowed here</code> Handling</a></li>
<li><a href="parser.html#sec:Regular_Expression">5.3.3. Regular Expression</a></li>
<li><a href="parser.html#sec:Unicode">5.3.4. Unicode</a></li>
<li><a href="parser.html#sec:Literals">5.3.5. Literals</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Modifiers">5.4. Modifiers</a></li>
<li><a href="parser.html#sec:Conflict_Resolutions">5.5. Conflict Resolutions</a>
<ul class="sectlevel3">
<li><a href="parser.html#sec:Reserved_Keywords_vs__Identifier_Names">5.5.1. Reserved Keywords vs. Identifier Names</a></li>
<li><a href="parser.html#sec:Operators_and_Generics">5.5.2. Operators and Generics</a></li>
</ul>
</li>
<li><a href="parser.html#sec:Content_Assist_Parser">5.6. Content-Assist Parser</a></li>
</ul>
</li>
<li><a href="type_system.html#_type-system">6. Type System</a>
<ul class="sectlevel2">
<li><a href="type_system.html#sec:Type_Model_and_Grammar">6.1. Type Model and Grammar</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Model_Overview">6.1.1. Type Model Overview</a></li>
<li><a href="type_system.html#sec:Built_in_Types">6.1.2. Built-in and Primitive Types</a></li>
<li><a href="type_system.html#sec:Type_Model_DSL">6.1.3. Type Model DSL</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Type_System_Implementation">6.2. Type System Implementation</a></li>
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal">6.3. Type Inference of AST</a>
<ul class="sectlevel3">
<li><a href="type_system.html#sec:Type_Inference_combined_with_AST_Traversal__Background">6.3.1. Background</a></li>
<li><a href="type_system.html#sec:Triggering_Type_Inference_of_AST">6.3.2. Triggering</a></li>
<li><a href="type_system.html#sec:Traversal_Order_During_Type_Inference_of_AST">6.3.3. Traversal Order</a></li>
<li><a href="type_system.html#sec:Cross_References_During_Type_Inference_of_AST">6.3.4. Cross-References</a></li>
<li><a href="type_system.html#sec:Function_Accessor_Bodies_During_Type_Inference_of_AST">6.3.5. Function/Accessor Bodies</a></li>
<li><a href="type_system.html#sec:Poly_Expressions_During_Type_Inference_of_AST">6.3.6. Poly Expressions</a></li>
<li><a href="type_system.html#sec:Constraint_Solver_used_During_Type_Inference_of_AST">6.3.7. Constraint Solver</a></li>
<li><a href="type_system.html#sec:Type_Guards_During_Type_Inference_of_AST">6.3.8. Type Guards</a></li>
</ul>
</li>
<li><a href="type_system.html#sec:Structural_Typing">6.4. Structural Typing</a></li>
</ul>
</li>
<li><a href="type_index.html#_type-index">7. Type Index</a>
<ul class="sectlevel2">
<li><a href="type_index.html#sec:Type_Index_Design_Rationale">7.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Getting_the_Xtext_Index_Content_IResourceDescriptions">7.1.1. Getting the Xtext Index (<code>IResourceDescriptions</code>) Content</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Design_Overview">7.2. Design Overview</a></li>
<li><a href="type_index.html#sec:N4JS_Resource_Load_States">7.3. N4JS Resource Load States</a></li>
<li><a href="type_index.html#sec:Type_Builder">7.4. Types Builder</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Type_Inference_not_allowed_in_Type_Builder">7.4.1. Type Inference not allowed in Types Builder</a></li>
<li><a href="type_index.html#sec:ComputedTypeReferences">7.4.2. Deferred Type References</a></li>
<li><a href="type_index.html#sec:Use_cases_of_ComputedTypeRef">7.4.3. Use cases of DeferredTypeRef</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview">7.5. Incremental Builder (Overview)</a>
<ul class="sectlevel3">
<li><a href="type_index.html#sec:Incremental_Builder_Overview__XtextBuilder">7.5.1. XtextBuilder</a></li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__IBuilderState">7.5.2. IBuilderState</a>
<ul class="sectlevel4">
<li><a href="type_index.html#copy-and-update-xtext-index">7.5.2.1. Copy and Update Xtext Index</a></li>
<li><a href="type_index.html#build-state-setup-phase">7.5.2.2. Build State Setup Phase</a></li>
<li><a href="type_index.html#process-queued-uris">7.5.2.3. Process Queued URIs</a></li>
<li><a href="type_index.html#queueing-affected-resources">7.5.2.4. Queueing Affected Resources</a></li>
</ul>
</li>
<li><a href="type_index.html#sec:Incremental_Builder_Overview__Example">7.5.3. Example</a></li>
</ul>
</li>
<li><a href="type_index.html#dirty-state-handling">7.6. Dirty state handling</a>
<ul class="sectlevel3">
<li><a href="type_index.html#use-case-restoring-types-from-user-data">7.6.1. Use case: Restoring types from user data</a></li>
<li><a href="type_index.html#use-case-updating-the-xtext-index">7.6.2. Use case: Updating the Xtext index</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="project_model.html#_project-model">8. Project Model</a>
<ul class="sectlevel2">
<li><a href="project_model.html#sec:Package_json">8.1. Package.json File</a></li>
<li><a href="project_model.html#_accessing-project-information">8.2. Accessing Project Information</a>
<ul class="sectlevel3">
<li><a href="project_model.html#sec:IN4JSCore">8.2.1. IN4JSCore</a></li>
<li><a href="project_model.html#sec:N4JSModel">8.2.2. N4JSModel</a></li>
<li><a href="project_model.html#sec:N4JSWorkspace">8.2.3. N4JSWorkspace</a></li>
<li><a href="project_model.html#sec:N4JSProject">8.2.4. N4JSProject</a></li>
<li><a href="project_model.html#sec:SourceContainer">8.2.5. SourceContainer</a></li>
<li><a href="project_model.html#sec:N4JSProjectsStateHelper">8.2.6. N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:Caching">8.3. Caching</a>
<ul class="sectlevel3">
<li><a href="project_model.html#_caching-of-externallibraryworkspace">8.3.1. Caching of ExternalLibraryWorkspace</a></li>
<li><a href="project_model.html#_caching-of-n4jsprojectsstatehelper">8.3.2. Caching of N4JSProjectsStateHelper</a></li>
</ul>
</li>
<li><a href="project_model.html#sec:WildcardPathFilter">8.4. WildcardPathFilter</a></li>
<li><a href="project_model.html#sec:ProjectUtils">8.5. ProjectUtils</a></li>
</ul>
</li>
<li><a href="#_binding">9. Binding</a>
<ul class="sectlevel2">
<li><a href="#sec:Binding_Design_Rationale">9.1. Design Rationale</a></li>
<li><a href="#sec:Binding_to_Members">9.2. Binding to Members</a></li>
<li><a href="#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></li>
<li><a href="#chap:Statics">9.4. Static Member Binding</a></li>
<li><a href="#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></li>
<li><a href="#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></li>
<li><a href="#sec:Member_Scope_Example">9.7. Member Scope Example</a></li>
<li><a href="#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></li>
<li><a href="#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></li>
<li><a href="#sec:Building">9.10. Building</a>
<ul class="sectlevel3">
<li><a href="#sec:Build_Phases">9.10.1. Build Phases</a></li>
<li><a href="#sec:Build_Scenarios">9.10.2. Build Scenarios</a></li>
<li><a href="#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></li>
</ul>
</li>
<li><a href="#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a>
<ul class="sectlevel3">
<li><a href="#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></li>
<li><a href="#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></li>
<li><a href="#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></li>
<li><a href="#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="validation.html#_validation">10. Validation</a>
<ul class="sectlevel2">
<li><a href="validation.html#sec:validation_overview">10.1. Validation overview</a></li>
<li><a href="validation.html#sec:validation_control_flow">10.2. Validation control flow</a></li>
<li><a href="validation.html#sec:validation_issue_ids">10.3. Issue IDs and Messages</a></li>
<li><a href="validation.html#sec:validation_usage_patterns">10.4. Usage Pattern</a></li>
<li><a href="validation.html#sec:validation_links">10.5. Links</a></li>
</ul>
</li>
<li><a href="references.html#_references">11. References</a>
<ul class="sectlevel2">
<li><a href="references.html#sec:usecases">11.1. Use cases</a></li>
<li><a href="references.html#sec:calculation_algorithm">11.2. Calculation algorithm</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Xtext_default_implementation">11.2.1. Xtext default implementation</a></li>
<li><a href="references.html#sec:N4_implementation">11.2.2. N4JS implementation</a></li>
</ul>
</li>
<li><a href="references.html#sec:PerformanceOfDependencyCalculation">11.3. Performance Of Dependency Calculation</a></li>
<li><a href="references.html#sec:kinds_of_references">11.4. Kinds of references</a>
<ul class="sectlevel3">
<li><a href="references.html#sec:Cross_References_to_be_ignored">11.4.1. Cross References to be ignored</a></li>
<li><a href="references.html#sec:Cross_References_to_be_handled">11.4.2. Cross References to be handled</a></li>
</ul>
</li>
<li><a href="references.html#sec:transitive_dependencies">11.5. Transitive dependencies</a></li>
<li><a href="references.html#sec:find-references">11.6. Find references</a>
<ul class="sectlevel3">
<li><a href="references.html#_background">11.6.1. Background</a></li>
<li><a href="references.html#_how-find-references-work">11.6.2. How Find References Work</a>
<ul class="sectlevel4">
<li><a href="references.html#_step-1-convert-cursor-position-to-declared-element">11.6.2.1. Step 1: Convert Cursor Position to Declared Element</a></li>
<li><a href="references.html#_step-2-convert-declared-element-to-target-uris">11.6.2.2. Step 2: Convert Declared Element to Target URIs</a></li>
<li><a href="references.html#_step-3-filter-potential-resources">11.6.2.3. Step 3: Filter Potential Resources</a></li>
<li><a href="references.html#_step-4-search-references-in-resource">11.6.2.4. Step 4: Search References in Resource</a></li>
<li><a href="references.html#_limitations-and-possible-enhancements">11.6.2.5. Limitations and Possible Enhancements</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#_compilation">12. Compilation</a>
<ul class="sectlevel2">
<li><a href="compilation.html#chap:compilation">12.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:general_design_rationals">12.1.1. General design rationals</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:logging_and_error_reporting">12.1.1.1. Logging and error reporting</a></li>
<li><a href="compilation.html#sec:progress_monitor">12.1.1.2. Progress monitor</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Xtext_Integration">12.1.2. Xtext Integration</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:xtext_default_behaviour">12.1.2.1. Xtext default behaviour</a></li>
<li><a href="compilation.html#sec:n4js_requirements">12.1.2.2. N4JS requirements</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_ui">12.1.2.3. Compiler discovery in UI</a></li>
<li><a href="compilation.html#sec:compiler_discovery_in_headless">12.1.2.4. Compiler discovery in headless</a></li>
<li><a href="compilation.html#sec:general_generator_implementation">12.1.2.5. General generator implementation</a></li>
<li><a href="compilation.html#sec:general_generator_activation">12.1.2.6. General generator activation</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Overview_of_Input_Models">12.1.3. Overview of the Input Models</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Core_Generator">12.2. Generators</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Compiler_Components">12.2.1. Generator Components</a></li>
<li><a href="compilation.html#sec:Generator_architecture">12.2.2. Generator architecture</a></li>
<li><a href="compilation.html#sec:Unified_Compiler_Configuration">12.2.3. Unified Compiler Configuration</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Transpilers">12.3. Transpilers</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Phases">12.3.1. Overview</a></li>
<li><a href="compilation.html#relation-between-ast-and-im">12.3.2. Relation between AST and IM</a></li>
<li><a href="compilation.html#implementation-overview">12.3.3. Implementation Overview</a></li>
<li><a href="compilation.html#sec:Guidelines_for_Implementing_Transformations">12.3.4. Guidelines for Implementing Transformations</a></li>
<li><a href="compilation.html#symbol-table-in-the-im">12.3.5. Symbol Table in the IM</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:N4JS_to_EcmaScript_Transpiler">12.4. N4JS-to-EcmaScript Transpiler</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:Overview_of_Transformations">12.4.1. Overview of Transformations</a></li>
<li><a href="compilation.html#sec:Transpiling_members">12.4.2. Transpiling members</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Transpiling_members__Delegating_members">12.4.2.1. Techniques for special member handling</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Partial_shadowing_of_getter_setter_pairs">12.4.2.2. Partial shadowing</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Consuming_or_inheriting_members_of_an_interface">12.4.2.3. Consuming or inheriting members of an interface</a></li>
<li><a href="compilation.html#sec:Transpiling_members__Static_polyfill">12.4.2.4. Static polyfill</a></li>
<li><a href="compilation.html#sec:Transpiling_members__API_implementation_stubs">12.4.2.5. API / implementation stubs</a></li>
</ul>
</li>
<li><a href="compilation.html#sec:Support_for_incomplete_API_implementation_testing_in_the_N4JS_to_EcmaScript_5_Transpiler">12.4.3. Support for incomplete API implementation testing</a>
<ul class="sectlevel4">
<li><a href="compilation.html#sec:Modifications_in_Impl_projects">12.4.3.1. Modifications in Impl projects</a></li>
<li><a href="compilation.html#sec:Implementation_of_stub_generation">12.4.3.2. Implementation of stub-generation</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="compilation.html#sec:n4jsc_Headless_Compiler_Interface">12.5. n4jsc Headless Compiler Interface</a>
<ul class="sectlevel3">
<li><a href="compilation.html#sec:building_the_headless_compiler">12.5.1. building the headless compiler</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="execution.html#_execution">13. Execution</a>
<ul class="sectlevel2">
<li><a href="execution.html#sec:N4JS_Project_Execution_And_Linking_Model">13.1. N4JS Project Execution And Linking Model</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4JS_Execution_With_NodeJS">13.1.1. N4JS Execution With NodeJS</a></li>
</ul>
</li>
<li><a href="execution.html#sec:N4JS_Execution_And_Linking_File">13.2. N4JS Execution And Linking File</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:NodeJS_Specific_ELF">13.2.1. NodeJS Specific ELF</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runners-execution">13.3. Runners</a>
<ul class="sectlevel3">
<li><a href="execution.html#subsec:N4_Runtime_Environments_Convention">13.3.1. N4 Runtime Environments Convention</a></li>
<li><a href="execution.html#subsec:Passing_Information_from_IDE_to_Execution_Code_in_Runtime_Environment">13.3.2. Passing Information from IDE to Execution Code in Runtime Environment</a></li>
<li><a href="execution.html#subsec:Runners_Design">13.3.3. Runners Design</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Legacy_Execution_Engine">13.4. Legacy Execution Engine</a></li>
<li><a href="execution.html#sec:Design">13.5. Design</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Usage_Outside_N4JSIDE">13.5.1. Usage Outside N4JSIDE</a>
<ul class="sectlevel4">
<li><a href="execution.html#sec:Use_Node_with_Maven">13.5.1.1. Use Node with Maven</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Usage_Inside_N4JSIDE">13.5.2. Usage Inside N4JSIDE</a></li>
</ul>
</li>
<li><a href="execution.html#sec:Runtime_Injection">13.6. Runtime Injection</a>
<ul class="sectlevel3">
<li><a href="execution.html#sec:Running_String_Code">13.6.1. Running String Code</a></li>
<li><a href="execution.html#sec:Running_File_Code">13.6.2. Running File Code</a></li>
<li><a href="execution.html#sec:Injection_Code_Example">13.6.3. Injection Code Example</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#_tests">14. Tests</a>
<ul class="sectlevel2">
<li><a href="tests.html#sec:Performance_Tests">14.1. Performance Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Synthetic_Performance_Tests">14.1.1. Synthetic Performance Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Design_of_Generator">14.1.1.1. Design of Generator</a></li>
<li><a href="tests.html#sec:Design_of_Performance_Test_Execution">14.1.1.2. Design of Performance Test Configuration and Execution</a></li>
<li><a href="tests.html#sec:JUnit_Configuration">14.1.1.3. JUnit Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Test_Configuration">14.1.1.4. JUnitBenchmark Test Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Report_Configuration">14.1.1.5. JUnitBenchmark Report Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Run_Configuration">14.1.1.6. JUnitBenchmark Run Configuration</a></li>
<li><a href="tests.html#sec:JUnitBenchmark_Example">14.1.1.7. JUnitBenchmark Example</a></li>
<li><a href="tests.html#sec:Note_on_Jenkins_Job">14.1.1.8. Note on Jenkins Job</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:ECMA_Tests">14.2. ECMA Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Grammar_Tests">14.2.1. Grammar Tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Negative_Tests">14.2.1.1. Negative Tests</a></li>
<li><a href="tests.html#sec:Test_Exclusion">14.2.1.2. Test Exclusion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Integration_Tests">14.3. Integration Tests</a></li>
<li><a href="tests.html#sec:Test_Helpers">14.4. Test Helpers</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Parameterized_N4JS_Tests">14.4.1. Parameterized N4JS tests</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:ParameterizedXtextRunner">14.4.1.1. ParameterizedXtextRunner</a></li>
<li><a href="tests.html#sec:TestCodeProvider">14.4.1.2. TestCodeProvider</a></li>
<li><a href="tests.html#sec:Example_Of_Parameterized_Parser_Test">14.4.1.3. Example of parameterized parser test</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="tests.html#sec:Issue_Suppression">14.5. Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Tests">14.6. Xpect Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Xpect_Test_Setup">14.6.1. Xpect Test Setup</a></li>
<li><a href="tests.html#sec:Xpect_Issue_Suppression">14.6.2. Xpect Issue Suppression</a></li>
<li><a href="tests.html#sec:Xpect_Provided_Test_Methods">14.6.3. Xpect Provided Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#errors">14.6.3.1. errors</a></li>
<li><a href="tests.html#warnings">14.6.3.2. warnings</a></li>
</ul>
</li>
<li><a href="tests.html#sec:N4JS_Specific_Xpect_Test_Methods">14.6.4. N4JS Specific Xpect Test Methods</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:XPECT_noerrors">14.6.4.1. noerrors and nowarnings</a></li>
<li><a href="tests.html#sec:XPECT_scope">14.6.4.2. scope</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithPosition">14.6.4.3. scopeWithPosition</a></li>
<li><a href="tests.html#sec:XPECT_scopeWithResource">14.6.4.4. scopeWithResource</a></li>
<li><a href="tests.html#sec:XPECT_binding">14.6.4.5. binding</a></li>
<li><a href="tests.html#sec:XPECT_linkedPathname">14.6.4.6. linkedPathname</a></li>
<li><a href="tests.html#sec:XPECT_type_of">14.6.4.7. type of</a></li>
<li><a href="tests.html#sec:XPECT_expectedType">14.6.4.8. expectedType</a></li>
<li><a href="tests.html#sec:XPECT_elementKeyword">14.6.4.9. elementKeyword</a></li>
<li><a href="tests.html#sec:XPECT_accessModifier">14.6.4.10. accessModifier</a></li>
<li><a href="tests.html#sec:XPECT_compileResult">14.6.4.11. compileResult</a></li>
<li><a href="tests.html#sec:XPECT_output">14.6.4.12. output</a></li>
<li><a href="tests.html#sec:XPECT_outputRegEx">14.6.4.13. outputRegEx</a></li>
<li><a href="tests.html#sec:XPECT_calculatedAccessModifier">14.6.4.14. calculatedAccessModifier</a></li>
<li><a href="tests.html#sec:XPECT_spec">14.6.4.15. spec</a></li>
<li><a href="tests.html#sec:XPECT_deadCode">14.6.4.16. deadCode</a></li>
<li><a href="tests.html#sec:XPECT_returnOrThrows">14.6.4.17. returnOrThrows</a></li>
<li><a href="tests.html#sec:XPECT_lint">14.6.4.18. lint</a></li>
<li><a href="tests.html#sec:XPECT_lintFails">14.6.4.19. lintFails</a></li>
</ul>
</li>
<li><a href="tests.html#sec:FIXME_Xpect_modifier">14.6.5. FIXME Xpect modifier</a></li>
<li><a href="tests.html#sec:Expectmatrix_Xpect_Test_Methods">14.6.6. Expectmatrix Xpect tests</a></li>
<li><a href="tests.html#xpect-lint-tests">14.6.7. Xpect Lint Tests</a></li>
</ul>
</li>
<li><a href="tests.html#xpect-proposal-tests">14.7. Xpect Proposal Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Validation_vs__Non_Validation">14.7.1. Validation vs. Non-Validation</a></li>
<li><a href="tests.html#sec:General_Proposal_Test_Features">14.7.2. General Proposal Test Features</a>
<ul class="sectlevel4">
<li><a href="tests.html#sec:Test_Variables">14.7.2.1. Test Variables</a></li>
<li><a href="tests.html#sec:Location_and_Selection">14.7.2.2. at – Location and Selection</a></li>
<li><a href="tests.html#sec:Multi_Line_Expectations_in_Proposal_Tests">14.7.2.3. Multi Line Expectations in Proposal Tests</a></li>
<li><a href="tests.html#sec:Timeout">14.7.2.4. Timeout and Performance</a></li>
</ul>
</li>
<li><a href="tests.html#proposals-verify-existence-of-proposals">14.7.3. proposals – Verify Existence of Proposals</a></li>
<li><a href="tests.html#sec:Verify_displayed_string">14.7.4. display – Verify displayed string</a></li>
<li><a href="tests.html#sec:Apply_Proposal">14.7.5. apply – Apply Proposal</a>
<ul class="sectlevel4">
<li><a href="tests.html#resource-application-in-other-files">14.7.5.1. resource – application in other files</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Content_Assist_Cycling">14.7.6. kind – Content Assist Cycling</a></li>
<li><a href="tests.html#fileValidVerify-validation-status">14.7.7. fileValid – Verify validation status</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Apply_Proposal_And_Execute_Tests">14.8. Apply Proposal And Execute Tests</a></li>
<li><a href="tests.html#sec:Organize_Imports_Test">14.9. Organize Imports Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#organizeimports">14.9.1. organizeImports</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Access_Control_Test">14.10. Access Control Test</a>
<ul class="sectlevel3">
<li><a href="tests.html#test-scenarios">14.10.1. Test Scenarios</a></li>
<li><a href="tests.html#n4js-code-generator">14.10.2. N4JS Code Generator</a></li>
<li><a href="tests.html#xtext-issue-matcher">14.10.3. Xtext Issue Matcher</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Smoke_Tests">14.11. Smoke Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#how-to-handle-smoke-test-errors">14.11.1. How to handle smoke test errors?</a></li>
<li><a href="tests.html#smoketester-and-exceptionanalyzer">14.11.2. SmokeTester and ExceptionAnalyzer</a></li>
</ul>
</li>
<li><a href="tests.html#sec:UI_Tests_with_SWTBot">14.12. UI Tests with SWTBot</a>
<ul class="sectlevel3">
<li><a href="tests.html#writing-swtbot-tests">14.12.1. Writing SWTBot Tests</a></li>
<li><a href="tests.html#running-swtbot-tests">14.12.2. Running SWTBot Tests</a></li>
</ul>
</li>
<li><a href="tests.html#sec:Debugging_UI_Tests">14.13. Debugging UI Tests</a>
<ul class="sectlevel3">
<li><a href="tests.html#sec:Connecting_to_the_X_server_on_the_build_node">14.13.1. Connecting to the X-server on the build-node</a></li>
<li><a href="tests.html#sec:Tools_to_investigate_the_java_stack">14.13.2. Tools to investigate the java-stack</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_ui-concepts">15. UI Concepts</a>
<ul class="sectlevel2">
<li><a href="ui_concepts.html#sec:User_Interface_Concepts">15.1. User Interface Concepts</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#sec:Eclipse_UI_Concepts">15.1.1. Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Label_Provider">15.1.1.1. Label Provider</a></li>
<li><a href="ui_concepts.html#sec:Markers">15.1.1.2. Markers</a></li>
<li><a href="ui_concepts.html#sec:Commands__Toolbar_and_Menus">15.1.1.3. Commands, Toolbar and Menus</a></li>
<li><a href="ui_concepts.html#sec:Content_Assist">15.1.1.4. Content Assist</a></li>
<li><a href="ui_concepts.html#sec:Quick_Fixes">15.1.1.5. Quick Fixes</a></li>
<li><a href="ui_concepts.html#sec:Quick_Assist">15.1.1.6. Quick Assist</a></li>
<li><a href="ui_concepts.html#sec:Clean_Up_Actions">15.1.1.7. Clean Up Actions</a></li>
<li><a href="ui_concepts.html#sec:Save_Actions">15.1.1.8. Save Actions</a></li>
<li><a href="ui_concepts.html#sec:Auto_Edit">15.1.1.9. Auto Edit</a></li>
<li><a href="ui_concepts.html#sec:Template_Proposals">15.1.1.10. Template Proposals</a></li>
<li><a href="ui_concepts.html#sec:Outline_View___Quick_Outline">15.1.1.11. Outline View / Quick Outline</a></li>
<li><a href="ui_concepts.html#sec:Navigator__Package_Explorer__Project_Explorer">15.1.1.12. Navigator, Package Explorer, Project Explorer</a></li>
<li><a href="ui_concepts.html#sec:Hyperlinking_and_Navigation">15.1.1.13. Hyperlinking and Navigation</a></li>
<li><a href="ui_concepts.html#sec:Syntax_and_Semantic_Coloring">15.1.1.14. Syntax and Semantic Coloring</a></li>
<li><a href="ui_concepts.html#sec:Code_Formatter">15.1.1.15. Code Formatter</a></li>
<li><a href="ui_concepts.html#sec:Wizards">15.1.1.16. Wizards</a></li>
<li><a href="ui_concepts.html#sec:Cheat_Sheets">15.1.1.17. Cheat Sheets</a></li>
<li><a href="ui_concepts.html#sec:Context_sensitive_Help">15.1.1.18. Context-sensitive Help</a></li>
<li><a href="ui_concepts.html#sec:Hovers">15.1.1.19. Hovers</a></li>
<li><a href="ui_concepts.html#sec:Folding">15.1.1.20. Folding</a></li>
<li><a href="ui_concepts.html#sec:Customizable_validation___severity">15.1.1.21. Customizable validation / severity</a></li>
<li><a href="ui_concepts.html#sec:Proposals">15.1.1.22. Proposals</a></li>
</ul>
</li>
<li><a href="ui_concepts.html#sec:Non_Eclipse_UI_Concepts">15.1.2. Non-Eclipse UI Concepts</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#sec:Overlays">15.1.2.1. Overlays</a></li>
<li><a href="ui_concepts.html#sec:Goto__Inferred__Type">15.1.2.2. Goto (Inferred) Type</a></li>
<li><a href="ui_concepts.html#sec:Postfix_Completion">15.1.2.3. Postfix Completion</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="ui_concepts.html#_user-interface-resources">15.2. User Interface Resources</a>
<ul class="sectlevel3">
<li><a href="ui_concepts.html#_icons">15.2.1. Icons</a>
<ul class="sectlevel4">
<li><a href="ui_concepts.html#_eclipse-platform-icons">15.2.1.1. Eclipse Platform Icons</a></li>
<li><a href="ui_concepts.html#_n4js-specific-icons">15.2.1.2. N4JS Specific Icons</a></li>
<li><a href="ui_concepts.html#_high-resolution-icons">15.2.1.3. High Resolution Icons</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="formatting.html#_formatting">16. Formatting</a>
<ul class="sectlevel2">
<li><a href="formatting.html#sec:FmtObjective">16.1. Objective</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:FmtFormatting_Comments">16.1.1. Formatting Comments</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtArchitecture">16.2. Architecture</a>
<ul class="sectlevel3">
<li><a href="formatting.html#sec:Implementation_example">16.2.1. Implementation example</a></li>
</ul>
</li>
<li><a href="formatting.html#sec:FmtFormatter_Implementation_Guidelines">16.3. Formatter Implementation Guidelines</a></li>
<li><a href="formatting.html#sec:FmtConfiguration">16.4. Configuration</a></li>
<li><a href="formatting.html#sec:FmtUI_Integration">16.5. UI Integration</a></li>
<li><a href="formatting.html#sec:FmtUnit_Testing_with_Xpect">16.6. Unit Testing with Xpect</a></li>
</ul>
</li>
<li><a href="external_libraries.html#_external-libraries">17. External Libraries</a>
<ul class="sectlevel2">
<li><a href="external_libraries.html#sec:Major_Components">17.1. Major Components</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:External_Resources">17.1.1. External Resources</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Workspace">17.1.2. External Library Workspace</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Store">17.1.3. External Library Preference Store</a></li>
<li><a href="external_libraries.html#subsec:npm_Manager">17.1.4. Library Manager</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Builder_Helper">17.1.5. External Library Builder</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Xtext_Index_Persister">17.1.6. External Library Xtext Index Persister</a></li>
<li><a href="external_libraries.html#subsec:External_Library_Preference_Page">17.1.7. External Library Preference Page</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:Headless_External_Library_Support">17.2. Headless External Library Support</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#_custom-npm-settings">17.2.1. Custom npm settings</a></li>
</ul>
</li>
<li><a href="external_libraries.html#sec:lmFutureWork">17.3. Future Work</a>
<ul class="sectlevel3">
<li><a href="external_libraries.html#subsec:lmMultipleDependencyScope">17.3.1. Multiple Dependency Scope</a></li>
<li><a href="external_libraries.html#subsec:lmRunTestsFromLibrary">17.3.2. Run Tests from TestLibrary</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Support">18. JSON Support</a>
<ul class="sectlevel2">
<li><a href="json_support.html#sec:JSON_Parser">18.1. JSON Parser</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Parser_Unicode_Escaping">18.1.1. Escaping Unicode Control Characters in String Literals</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Empty_Text">18.1.2. Empty Text</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Nested_Structures">18.1.3. Nested Structures</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Whitespace">18.1.4. Whitespace</a></li>
<li><a href="json_support.html#sec:JSON_Parser_Comments">18.1.5. Comments</a></li>
</ul>
</li>
<li><a href="json_support.html#sec:JSON_Language_Extensions">18.2. JSON Language Extensions</a>
<ul class="sectlevel3">
<li><a href="json_support.html#sec:JSON_Validator_Extensions">18.2.1. JSON Validator Extensions</a>
<ul class="sectlevel4">
<li><a href="json_support.html#sec:File_Specitic_Validator_Extensions">18.2.1.1. File-Specific Validator Extensions</a></li>
<li><a href="json_support.html#sec:JSON_Declarative_JSON_Validator_Extensions">18.2.1.2. Declarative JSON Validator Extensions</a></li>
</ul>
</li>
<li><a href="json_support.html#_json-resource-description-strategy">18.2.2. JSON Resource Description Strategy</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc">19. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#sec:Design_Rationale">19.1. Design Rationale</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_general-design">19.1.1. General Design</a></li>
<li><a href="jsdoc.html#sec:Type_Expressions">19.1.2. Type Expressions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="docexporter.html#_docexporter">20. DocExporter</a>
<ul class="sectlevel2">
<li><a href="docexporter.html#sec:Specification_Exporter">20.1. Specification Exporter</a></li>
</ul>
</li>
<li><a href="rename_refactoring.html#_rename-refactoring">21. Rename Refactoring</a>
<ul class="sectlevel2">
<li><a href="rename_refactoring.html#_rename-refactoring-ui-interaction">21.1. Rename Refactoring UI interaction</a></li>
<li><a href="rename_refactoring.html#_renameelementprocessor-interaction">21.2. RenameElementProcessor interaction</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#chap:flowgraphs">22. Flow Graphs</a>
<ul class="sectlevel2">
<li><a href="flow_graphs.html#sec:flowgraphs_overview">22.1. Flow graphs overview</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_internal-graph">22.1.1. Internal graph</a></li>
<li><a href="flow_graphs.html#_optimizations">22.1.2. Optimizations</a></li>
<li><a href="flow_graphs.html#_api-for-client-analyses">22.1.3. API for client analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_mapping-from-internal-to-ast-elements">22.1.3.1. Mapping from internal to AST elements</a></li>
<li><a href="flow_graphs.html#_graph-visitor">22.1.3.2. Graph visitor</a></li>
<li><a href="flow_graphs.html#_graph-explorer">22.1.3.3. Graph explorer</a></li>
<li><a href="flow_graphs.html#_branch-walker">22.1.3.4. Branch walker</a></li>
<li><a href="flow_graphs.html#_example-1-compute-string-for-each-path">22.1.3.5. Example 1: Compute string for each path</a></li>
<li><a href="flow_graphs.html#_path-quantor">22.1.3.6. Path quantor</a></li>
</ul>
</li>
<li><a href="flow_graphs.html#_control-flow-analyses">22.1.4. Control flow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_dead-code-analysis">22.1.4.1. Dead code analysis</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="flow_graphs.html#sec:dataflow">22.2. Dataflow</a>
<ul class="sectlevel3">
<li><a href="flow_graphs.html#_dataflow-graph">22.2.1. Dataflow graph</a></li>
<li><a href="flow_graphs.html#_dataflow-analyses">22.2.2. Dataflow analyses</a>
<ul class="sectlevel4">
<li><a href="flow_graphs.html#_def-def-def-nothing-analysis">22.2.2.1. Def&#8594;Def / Def&#8594;Nothing analysis</a></li>
<li><a href="flow_graphs.html#_def-use-decl-analysis">22.2.2.2. Def|Use&#8592;Decl analysis</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="publish_npms.html#sec:publish-npms-to-public">23. Publish npms</a>
<ul class="sectlevel2">
<li><a href="publish_npms.html#sec:publish-npms-n4js-maven">23.1. Publish n4js-libs to during  maven build</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Hints">Appendix A: Hints</a>
<ul class="sectlevel2">
<li><a href="appendix_a_hints.html#sec:XtextInjection">A.1. Xtext Injection</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:DI_MultipleInjectors_Singletons">A.1.1. Multiple Injectors and Singletons</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_avoid_duplicate_singletons">A.1.1.1. Avoiding duplicate singletons</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_binding_in_shared">A.1.1.1.1. Defining binding in the shared injector</a></li>
<li><a href="appendix_a_hints.html#sec:DI_binding_in_custom">A.1.1.1.2. Defining binding in the custom injector</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:DI_Hints">A.1.2. Dependency Injection Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle">A.1.2.1. Use DI in custom bundle, use DI with extensions</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_problem">A.1.2.1.1. Problem</a></li>
<li><a href="appendix_a_hints.html#sec:DI_custom_bundle_solution">A.1.2.1.2. Solution</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Access_Other_DSL_Injector">A.1.2.2. How do I get the Guice Injector of my language?</a>
<ul class="sectlevel5">
<li><a href="appendix_a_hints.html#sec:DSL_Injector_UI_context">A.1.2.2.1. UI context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_context">A.1.2.2.2. Non UI context but with injection context</a></li>
<li><a href="appendix_a_hints.html#sec:DSL_Injector_Non_UI_non_injection_context">A.1.2.2.3. Non UI context without injection context</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Cancel_Indicator">A.1.2.3. How do I get cancel indicators in different contexts?</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Eclipse">A.2. Eclipse</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#sec:Show_Xtext_Index">A.2.1. Show the current Xtext index</a></li>
<li><a href="appendix_a_hints.html#sec:Plugin_spy">A.2.2. Plug-in spy</a></li>
</ul>
</li>
<li><a href="appendix_a_hints.html#sec:Maven-hints">A.3. Maven</a>
<ul class="sectlevel3">
<li><a href="appendix_a_hints.html#how-to-check-for-maven-mojo-updates">A.3.1. How to check for Maven MOJO updates</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_module-loading">Appendix B: Module Loading</a>
<ul class="sectlevel2">
<li><a href="appendix_b_module_loading.html#sec:Dependency_Management">B.1. Dependency Management</a></li>
<li><a href="appendix_b_module_loading.html#ecmascript-modules">B.2. ECMAScript Modules</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES5_Modules_Systems">B.2.1. ES5 Modules Systems</a></li>
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules">B.2.2. ES6 Modules</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:ECMAScript_Module_Loaders">B.3. ECMAScript Module Loaders</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Module_Loaders">B.3.1. ES6 Module Loaders</a></li>
<li><a href="appendix_b_module_loading.html#sec:Polyfills_for_ES6_Module_Loaders">B.3.2. Polyfills for ES6 Module Loaders</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:es6_module_loader">B.3.2.1. es6-module-loader</a></li>
<li><a href="appendix_b_module_loading.html#sec:SystemJS">B.3.2.2. SystemJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Demo">B.3.2.3. Demo</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#case-study-typescript">B.4. Case Study : TypeScript</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:ES6_Modules_Support">B.4.1. ES6 Modules Support</a></li>
<li><a href="appendix_b_module_loading.html#sec:TypeScript_and_Module_Loading">B.4.2. TypeScript and Module Loading</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Cyclic_Dependencies">B.5. Cyclic Dependencies</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Setup">B.5.1. Setup</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpile_and_Execute">B.5.2. Transpile and Execute</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Module_Format___AMD">B.5.2.1. Module Format = AMD</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___CommonJS">B.5.2.2. Module Format = CommonJS</a></li>
<li><a href="appendix_b_module_loading.html#sec:Module_Format___SystemJS">B.5.2.3. Module Format = SystemJS</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Conclusion">B.5.3. Conclusion</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#system.register-as-transpilation-target">B.6. System.register as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#sec:Introduction">B.6.1. Introduction</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:External_Transpilers">B.6.1.1. External Transpilers</a></li>
<li><a href="appendix_b_module_loading.html#sec:Example_of_a_System_register_module">B.6.1.2. Example of a System.register module</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Structure_of_a_System_register_module">B.6.2. Structure of a System.register module</a></li>
<li><a href="appendix_b_module_loading.html#_transpilation-hints">B.6.3. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Handling_Imports">B.6.3.1. Handling Imports</a></li>
<li><a href="appendix_b_module_loading.html#sec:__exportFn__">B.6.3.2. &lt;&lt;exportFn&gt;&gt;</a></li>
<li><a href="appendix_b_module_loading.html#sec:Handling_Exports">B.6.3.3. Handling Exports</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:Examples_w__Circular_Dependencies">B.6.4. Examples w/ Circular Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:N4JS_Examples_w__Circular_Dependencies">B.6.5. N4JS Examples w/ Circular Dependencies</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Unresolved_Cyclic_Dependencies">B.6.5.1. Unresolved Cyclic Dependencies</a></li>
<li><a href="appendix_b_module_loading.html#sec:Variables___Functions">B.6.5.2. Examples with Variables &amp; Functions</a></li>
<li><a href="appendix_b_module_loading.html#sec:Classes">B.6.5.3. Examples with Classes</a></li>
<li><a href="appendix_b_module_loading.html#sec:Examples_with_SubClassing">B.6.5.4. Examples with SubClassing</a></li>
<li><a href="appendix_b_module_loading.html#sec:Miscellaneous">B.6.5.5. Miscellaneous</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources">B.6.6. Resources</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#sec:CommonJS_as_transpilation_target">B.7. CommonJS as transpilation target</a>
<ul class="sectlevel3">
<li><a href="appendix_b_module_loading.html#_introduction-2">B.7.1. Introduction</a></li>
<li><a href="appendix_b_module_loading.html#sec:Transpilation_Hints">B.7.2. Transpilation Hints</a>
<ul class="sectlevel4">
<li><a href="appendix_b_module_loading.html#sec:Import_Statements">B.7.2.1. Import Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Export_Statements">B.7.2.2. Export Statements</a></li>
<li><a href="appendix_b_module_loading.html#sec:Tracking_Live_Bindings">B.7.2.3. Tracking Live Bindings</a></li>
<li><a href="appendix_b_module_loading.html#sec:A_complete_example">B.7.2.4. A complete example</a></li>
</ul>
</li>
<li><a href="appendix_b_module_loading.html#_resources-2">B.7.3. Resources</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_c_license.html#sec:License">Appendix C: License</a></li>
<li><a href="appendix_d_acronyms.html#sec:Acronyms">Appendix D: Acronyms</a></li>
<li><a href="appendix_e_bibliography_and_footnotes.html#_bibliography-and-footnotes">Appendix E: Bibliography and Footnotes</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_binding"><a class="anchor" href="#_binding"></a><a class="link" href="#_binding">9. Binding</a></h2>
<div class="sectionbody">
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title=""></i>
</td>
<td class="content">
This section may be outdated!
</td>
</tr>
</table>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Binding_Design_Rationale"><a class="anchor" href="#sec:Binding_Design_Rationale"></a><a class="link" href="#sec:Binding_Design_Rationale">9.1. Design Rationale</a></h3>
<div class="paragraph">
<p>Binding references to declarations follows the Xtext mechanism based on local <code>N4JSScopeProvider</code> and a global <code>N4JSGlobalScopeProvider</code> scope providers. The basic question is: to which elements are references bound to. This in particular interesting for all kind of type declarations, including functions as they are interpreted as types. These declarations are Janus-faced: On the one side, they are targets of type references as <code>Type</code>, and on the other side they can also be target of identifier references bound to some so called <code>IdentifiableElement</code>. As explained in <a href="#_type_index">[_type_index]</a>, special type objects (<code>TClass</code> etc.) are created from the original declarations. These type objects are used as targets for both kind of references. The following table summarizes the reference-target relations relevant for N4JS (not the standalone type grammar).</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">Table 4. N4JS Cross References</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Reference</th>
<th class="tableblock halign-left valign-top">Target Type</th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">N4JS</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ImportDeclaration.importedModule</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TModule</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">NamedImportSpecifier.importedElement</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">types.IdentifiableElement</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">IdentifierRef.id</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">types.IdentifiableElement</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ParameterizedPropertyAccessExpression.property</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">types.TMethod</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">PropertyAccessExpression.property</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">types.TMember</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">N4Getter/N4SetterDeclaration.field</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">N4FieldDeclaration</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Continue/Break-Statement.label</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">LabelledStatement</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" colspan="2"><p class="tableblock">Type Expressions</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ParameterizedTypeRef.declaredType</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Type</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#fig:cd_scoping">Overview Scoping Package</a> gives an overview over the most important classes in the scoping package, with the <code>N4JSScopeProvider</code> and the used customized scopes created by the scope providers.</p>
</div>
<div id="fig:cd_scoping" class="imageblock center">
<div class="content">
<img src="chapters/09_binding/images/cd_scoping.svg" alt="cd scoping">
</div>
<div class="title">Figure 21. Overview Scoping Package</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Binding_to_Members"><a class="anchor" href="#sec:Binding_to_Members"></a><a class="link" href="#sec:Binding_to_Members">9.2. Binding to Members</a></h3>
<div class="paragraph">
<p>Members of different types, such as classes and also record types or enumerations, are bound using the <code>MemberScopeProvider</code>. This often returns a <code>MemberScope</code>, which directly works on the members. Most types with members are implemented by subclasses of <code>ContainerType</code>, using <code>CollectMembersHelper</code> to collect all members and <code>FindMemberHelper</code> for retrieving a member by its name via <code>ContainerTypes</code>. Ensure that when types with members are added to override appropriate methods in all of these related classes (e.g., <code>CollectMembersHelper</code>, <code>AbstractHierachyTraverser</code> and <code>FindMemberHelper</code> uses polymorphic dispatch to handle different subtypes – so you won’t be able to find a member if you do not adjust these helpers).</p>
</div>
</div>
<div class="sect2">
<h3 id="sec:Binding_Getter_Setter"><a class="anchor" href="#sec:Binding_Getter_Setter"></a><a class="link" href="#sec:Binding_Getter_Setter">9.3. Getter / Setter Binding</a></h3>
<div class="paragraph">
<p>For customized binding of getters / setters, see <a href="#sec:Field_Accessors">Accessors</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="chap:Statics"><a class="anchor" href="#chap:Statics"></a><a class="link" href="#chap:Statics">9.4. Static Member Binding</a></h3>
<div class="paragraph">
<p>For customized binding of static members, see <a href="#sec:Static_Members">Static Members</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="sec:Binding_Enumeration"><a class="anchor" href="#sec:Binding_Enumeration"></a><a class="link" href="#sec:Binding_Enumeration">9.5. Enumeration Literals Binding</a></h3>
<div class="ulist">
<ul>
<li>
<p>introduced new type ref EnumTypeRef: it behaves comparable to ClassifierTypeRef, but with the difference that the MemberScopeProvider filters for a given EnumTypeRef filters all literals of the contained TEnum (in comparison the MemberScopeProvider filters for a given ClassifierTypeRef all static members of the contained classifier)</p>
</li>
<li>
<p>it isn’t possible to access literals on a enumeration literal itself, although this literal is typed as TEnum (that contains TEnumLiterals)</p>
</li>
<li>
<p>as there are currently no additional fields and operations for enumeration literals defined (in Java there is name and value()), the scope for literals is currently empty</p>
</li>
</ul>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Accessibility_of_types_and_members"><a class="anchor" href="#sec:Accessibility_of_types_and_members"></a><a class="link" href="#sec:Accessibility_of_types_and_members">9.6. Accessibility of types and members</a></h3>
<div class="paragraph">
<p>Member access and type access has to be constrained and validated against the accessibility rules of N4JS. Therefore, the scoping annotates certain elements as erroneous to detect invalid references.</p>
</div>
<div class="paragraph">
<p>Basically two different approaches are used to implement that behavior:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The <code>VisibilityAwareTypeScope</code> and <code>VisibilityAwareMemberScope</code> decorate an existing scope to validate the result on access. This allows to lazily check the visibility of the returned element. If it is not accessible, it is wrapped in a <code>AbstractDescriptionWithError</code> which will be indentified as such by the <code>ErrorAwareLinkingService</code>. Before the binding is resolved and the EMF proxy is replaced, the error message is used to create an EMF diagnostic.</p>
</li>
<li>
<p>For other cases, the scopes are produced differently, e.g. if all elements are easily enumerable and have to be collected before the scope is created (e.g. for imported elements), the scoped elements are validated eagerly to put them into the correct layer of scopes. That is, the valid descriptions may shadow the invalid description. Since there are more error conditions for these cases, e.g. duplicate imports and similar cases, the accessibility is checked before the concrete member is accessed. All the instances <code>AbstractDescriptionWithError</code> are put into the <code>MapBasedScope</code> immediately.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In that sense, accessibility checks are basically implemented as decorators for the scoping itself. Bindings are established but flagged as errors.</p>
</div>
<div class="paragraph">
<p>Default visibility of members is calculated in <code>Types.xcore</code> (in <code>getTypeAccessModifier</code> and <code>getMemberAccessModifier</code> etc.). Visibility is checked in <code>org.eclipse.n4js.scoping.accessModifiers.MemberVisibilityChecker</code> and validators.</p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Member_Scope_Example"><a class="anchor" href="#sec:Member_Scope_Example"></a><a class="link" href="#sec:Member_Scope_Example">9.7. Member Scope Example</a></h3>
<div class="paragraph">
<p>In this section, we are going to have a look at the creation process of <code>MemberScope</code>.</p>
</div>
<div class="listingblock">
<div class="title">C.n4js</div>
<div class="content">
<pre class="highlight"><code>export public class C {
	 private m1: int;
	 public m2: int;
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Test.n4js</div>
<div class="content">
<pre class="highlight"><code>import { C } from "C";

let c: C = new C();
c.m1;  // Error -&gt; The field m1 is not visible
c.m2;  // OK    -&gt; m2 is visible at this context</code></pre>
</div>
</div>
<div class="paragraph">
<p>Assume that we need to figure out to which element the <code>ParameterizedPropertyAccessExpression c.m1</code> in the <code>ExpressionStatement c.m1</code> binds to. To answer this question, <code>N4JSScopeProvider.getScope(context, reference)</code> is triggered whereby <code>context</code> is the <code>ParameterizedPropertyAccessExpression</code> and <code>reference</code> is <code>EReference property</code> (<code>property</code> is the cross-reference element defined in <code>ParameterizedPropertyAccessExpression</code> 's grammar).</p>
</div>
<div class="paragraph">
<p><code>N4JSScopeProvider.getScope(context, reference)</code> does not implement the scoping but delegates to corresponding methods based on the type of <code>context</code>. In our example, since <code>context</code> is a <code>ParameterizedPropertyAccessExpression</code>, the scoping logic is delegated to the method that creates a <strong>MemberScope</strong> for the context <code>ParameterizedPropertyAccessExpression c.m1</code> based on the receiver type of <code>c</code> which is class <code>C</code>.
The resulting scope instance returned by <code>N4JSScopeProvider.getScope()</code> in our example is of type <code>TypingStrategyAwareMemberScope</code> as shown in <a href="#fig:memberscope-example">Member scope hierarchy</a> .</p>
</div>
<div id="fig:memberscope-example" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/09_binding/images/memberscope_example.svg" alt="memberscope example">
</div>
<div class="title">Figure 22. Member scope hierarchy</div>
</div>
<div class="paragraph">
<p>In the hierarchy, the top-level scope is the NULL scope. Directly below the NULL scope is a MemberScope which contains all members of <code>N4Object</code> since the class <code>C</code> implicitly inherits <code>N4Object</code>. The other <code>MemberScope</code> instance beneath contains all members of the class <code>C</code> <strong>regardless of their visibility</strong>. These members are <code>m1</code> and <code>m2</code>. While <code>m2</code> is can be accessed by <code>c.m2</code>, <code>m1</code> it not visible at <code>c.m1</code>. The <code>VisibilityAwareMemberScope</code> implements precisely this behavior. In particular, it returns all members of <code>C</code> that are visible at the current <code>context</code> (here the element <code>m2</code>),  while wrapping non-visible members (here the element <code>m</code>) in <code>InvisibleMemberDescription</code> instances. These <code>InvisibleMemberDescription</code> instances of type <code>IEObjectDescriptionWithError</code> contain issue code and error message related to accessibility problems and are recognized during the error-aware linking phase done by <code>ErrorAwareLinkingService</code>. It is worth to emphasize the motivation behind use of <code>IEObjectDescriptionWithError</code> is to provide more informative error messages to the user other than <em>Cannot reference element&#8230;&#8203;</em> Another example of <code>IEObjectDescriptionWithError</code> is <code>WrongWriteAccessDescription</code> that is used when we, try to write to a getter and no corresponding setter exists.</p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Scoping_for_Members_of_Composed_Type_Explained"><a class="anchor" href="#sec:Scoping_for_Members_of_Composed_Type_Explained"></a><a class="link" href="#sec:Scoping_for_Members_of_Composed_Type_Explained">9.8. Scoping for Members of Composed Type (Union/Intersection) Example</a></h3>
<div class="paragraph">
<p>In this section, we will have a look at how scoping is implemented for composed type, i.e. union or intersection type with an example of union type. Intersection is done similarly. Before reading this, it is strongly recommended to read <a href="#sec:Member_Scope_Example">Member Scope Example</a> first.</p>
</div>
<div class="listingblock">
<div class="title">Defs.n4js</div>
<div class="content">
<pre class="highlight"><code>export public class C {
	 private m1: int;
	 public m2: int;
}

export public class D {
	 private m1: int;
	 get m2(): int { return 42; };
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Test.n4js</div>
<div class="content">
<pre class="highlight"><code>import { C, D } from "Defs";

let cud : C|D;

cud.m2 = 10;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Assume that we need to find out to what element the <code>ParameterizedPropertyAccessExpression cud.m2</code> in the <code>ExpressionStatement cud.m2</code> binds to.
This is a question for scoping. Since the receiver type of <code>cud</code> is a union type <code>C|D</code>, a <code>UnionMemberScope</code> is created that contains two subscopes, each of which corresponds to an individual type in the union. The resulting scope hierarchy is graphically depicted in <a href="#fig:unionmemberscope-example">Union member scope hierarchy</a>.</p>
</div>
<div id="fig:unionmemberscope-example" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/09_binding/images/unionmemberscope_example.svg" alt="unionmemberscope example">
</div>
<div class="title">Figure 23. Union member scope hierarchy</div>
</div>
<div class="paragraph">
<p>The two subscopes are of type <code>TypingStrategyAwareMemberScope</code> and created exactly the same way as described in <a href="#sec:Member_Scope_Example">Member Scope Example</a>.
The <code>UnionMemberScope</code> instance contains a list of subscopes for all types involved in the union and is responsible for constructing an <code>IEObjectDescription</code> instance for <code>m2</code> by merging all members of the name <code>m2</code> found in all subscopes.
Merging members requires considering a variety of combinations (fields, setters getters, optional/variadic parameters etc.) and thus can become very complicated. To reduce the complexity, the recently refactored implementation splits the proccess into three separate steps.</p>
</div>
<div class="paragraph">
<p>Step 1: Collect information</p>
</div>
<div class="paragraph">
<p>During this phase, members with the name <code>m2</code> are looked up in each subscope and collected into an <code>ComposedMemberInfo</code> instance by <code>ComposedMemberInfoBuilder</code>.
The first subscope (left branch in the <a href="#fig:unionmemberscope-example">Union member scope hierarchy</a>) returns an <code>EObjectDescription</code> wrapping the <code>TField m2</code> of class <code>C</code> and hence <code>TField m2</code> is added to the <code>ComposedMemberInfo</code> instance. The second subscope (right branch in the <a href="#fig:unionmemberscope-example">Union member scope hierarchy</a>) returns a <code>WrongWriteAccessDescription</code> wrapping the <code>TGetter m2</code> of class <code>D</code> and hence <code>TGetter m2</code> is added to <code>ComposedMemberInfo</code> instance. The reason for <code>WrongWriteAccessDescription</code> because <code>cud.m2</code> is trying to write to the getter of the same name in <code>D</code>.</p>
</div>
<div class="paragraph">
<p>At the end of this step, two members <code>public TField m2: int</code> and <code>project TGetter m2(): int</code> are added to <code>ComposedMemberInfo</code>.</p>
</div>
<div class="paragraph">
<p>Step 2: Merge members</p>
</div>
<div class="paragraph">
<p>This phase merges members of the same name into a composed member based on the information about these members collected in Step 1. Note that merge rules can become quite complicated as many situations must be considered. Sometimes, it is not possible to merge at all. If the merge is possible, we need to consider the following properties, among others,</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Member kind: what kind of member is the merge result. For instance, what do we get when we merge a field with a setter?</p>
</li>
<li>
<p>Type of merge member: What is the return/parameter type of the merge result?</p>
</li>
<li>
<p>Accessibility: what is the accessibility of the merge result?</p>
</li>
<li>
<p>Optionality/Variadic: Should a parameter of the merge be optional or variadic?</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The actual merge rules are implemented in the class <code>UnionMemberFactory</code> which delegates to either of the classes <code>UnionMethodFactory</code>, <code>UnionFieldFactory</code>, <code>UnionGetterFactory</code> and <code>UnionSetterFactory</code>.</p>
</div>
<div class="paragraph">
<p>In our example,
The merge result of <code>public TField m2: int</code> and <code>project TGetter m2(): int</code> are merged into a <code>project TGetter m2: int</code> .</p>
</div>
<div class="paragraph">
<p>Step 3: Construct the scope entry</p>
</div>
<div class="paragraph">
<p>In this final step, the actual IEObjectDescription for <code>m2</code> is constructed. In our example, since there exists one subscope exposing an <code>EObjectDescriptionWithError</code> (here <code>WrongWriteAccessDescription</code>), the final result is an instance of <code>UnionMemberDescriptionWithError</code>. This error instance is recognized during the linking phase and the error message of the subscope regarding <code>WrongWriteAccessDescription</code> is displayed: <em>Union combines fields and getters with name m2 and therefore property m2 is read-only.</em></p>
</div>
<div class="paragraph">
<p>More details can be found in the API documentation in the code. A good starting point is the class <code>ComposedMemberScope</code>.</p>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Binding_of_Structurally_References_Types"><a class="anchor" href="#sec:Binding_of_Structurally_References_Types"></a><a class="link" href="#sec:Binding_of_Structurally_References_Types">9.9. Structurally References Types</a></h3>
<div class="paragraph">
<p>Scoping of structurally referenced types is similar to binding of members. The structural typing modifier basically filters the members of a type. That is, the structural modifier filters out all non-public members, and the field-only modifier only accept fields. Thus, similar to accessibility aware scoping (<a href="#sec:Accessibility_of_types_and_members">Accessibility of types and members</a>), the <code>TypingStrategyAwareMemberScope</code> encapsulates an original scope and applies these additional filters.</p>
</div>
<div class="paragraph">
<p>Bindings to additional members of a structurally referenced type is implemented in <code>MemberScopeProvider.members(ParameterizedTypeRefStructural ..)</code>. Note that the current implementation does not necessarily bind to the type model (TModule) instance, as these members are part of a type reference. That is, usually these bindings refer to the <a href="appendix_d_acronyms.html#AC">AST</a> elements. Thus, it is not possible to compare these members directly, instead, a structural comparison has to be applied.</p>
</div>
</div>
<div class="sect2">
<h3 id="sec:Building"><a class="anchor" href="#sec:Building"></a><a class="link" href="#sec:Building">9.10. Building</a></h3>
<div class="sect3">
<h4 id="sec:Build_Phases"><a class="anchor" href="#sec:Build_Phases"></a><a class="link" href="#sec:Build_Phases">9.10.1. Build Phases</a></h4>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Phase 0
</td>
<td class="hdlist2">
<p>Loading Resources</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Phase 1: prelinking
</td>
<td class="hdlist2">
<p>Create symbols for all resources, includes creation of temporary pre-linked type models</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Phase 2: linking
</td>
<td class="hdlist2">
<p>Resolve all links, includes fully-resolved typed models<br>
includes compilation</p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>That is, not each resource is loaded, pre-linked and linked separately. Instead, all resources are first loaded, then all resources are pre -inked, and only then all resources are linked.</p>
</div>
</div>
<div class="sect3">
<h4 id="sec:Build_Scenarios"><a class="anchor" href="#sec:Build_Scenarios"></a><a class="link" href="#sec:Build_Scenarios">9.10.2. Build Scenarios</a></h4>
<div class="paragraph">
<p>Consequences:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>do not try to set any types in types builder, only create symbols there (probably not even members of types)</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="sec:Lazy_linking_problem"><a class="anchor" href="#sec:Lazy_linking_problem"></a><a class="link" href="#sec:Lazy_linking_problem">9.10.3. Lazy linking problem</a></h4>
<div class="paragraph">
<p>Lazy linking proxies in the indes may trigger reloading of AST (which leads to invalid disconnected type models):</p>
</div>
<div class="paragraph">
<p>Lazy links (ending with |x in which x is an index entry of a temporary list used to resolve the link) must not be written into index.</p>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="sec:Proxies_and_Proxy_Resolution"><a class="anchor" href="#sec:Proxies_and_Proxy_Resolution"></a><a class="link" href="#sec:Proxies_and_Proxy_Resolution">9.11. Proxies and Proxy Resolution (Overview)</a></h3>
<div class="paragraph">
<p>Here we give a brief overview of the different kinds of proxies and when / how they are created and resolved.</p>
</div>
<div class="sect3">
<h4 id="xtexts-lazy-linking-proxies"><a class="anchor" href="#xtexts-lazy-linking-proxies"></a><a class="link" href="#xtexts-lazy-linking-proxies">9.11.1. Xtext’s Lazy Linking Proxies</a></h4>
<div class="ulist">
<ul>
<li>
<p>URI fragment is <code>|</code> <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>n</mi></math> (where <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>n</mi></math> is a non-negative integer).<br>
<code>platform:/resource/Project/src/A.n4js#|3</code></p>
</li>
<li>
<p>created by Xtext’s <code>LazyLinkingResource</code> in the AST after parsing (they are only ever created in the AST, but the types builder may copy them to the TModule, so they may appear there as well.</p>
</li>
<li>
<p>used to represent cross-references defined in the source code (i.e. name of an identifiable element used in source code to refer to that element).<br></p>
<div class="paragraph">
<p>Since the types builder sometimes copies proxies from AST to TModule (e.g. type of an element that was provided with an explicit type declaration in the source code), these proxies may also appear in the TModule, but only between the types builder phase and the end of the post-processing phase (or later, in case they are unresolvable).</p>
</div>
</li>
<li>
<p>resolution is handled by <code>#getEObject(String)</code> in <code>LazyLinkingResource</code>, which recognizes lazy linking URI fragments and then forwards them to <code>#getEObject(String,Triple)</code>, which in turn relies on the Xtext infrastructure.</p>
</li>
<li>
<p>latest time of resolution: post processing. After post processing has completed, they should all be gone (unless they are unresolvable, e.g. typo in source code).</p>
</li>
<li>
<p>fun facts:</p>
<div class="ulist">
<ul>
<li>
<p>the number after the pipe character is the index of a <code>Triple</code> stored in field <code>proxyInformation</code> in each <code>LazyLinkingResource</code>.</p>
</li>
<li>
<p>the resource given before the fragment (e.g. <code>A.n4js</code> in the above example) is not the resource the proxy is pointing to (i.e. the resource containing the target EObject), but the resource from where the link originates.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="standard-emf-proxies"><a class="anchor" href="#standard-emf-proxies"></a><a class="link" href="#standard-emf-proxies">9.11.2. Standard EMF Proxies</a></h4>
<div class="ulist">
<ul>
<li>
<p>URI fragment contains a path to an EObject, using reference names and indices:<br>
<code>platform:/resource/Project/src/A.n4js#/1/@topLevelTypes.1/@ownedMembers.0</code></p>
</li>
<li>
<p>created automatically by EMF</p>
<div class="ulist">
<ul>
<li>
<p>during deserialization of a TModule <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math> from the Xtext index for all references to a different TModule <math xmlns="http://www.w3.org/1998/Math/MathML"><msup><mi>M</mi><mi>'</mi></msup></math> (see <code>UserdataMapper</code>).</p>
</li>
<li>
<p>when unloading a resource.</p>
</li>
<li>
<p>&#8230;&#8203;</p>
</li>
</ul>
</div>
</li>
<li>
<p>used to represent</p>
<div class="ulist">
<ul>
<li>
<p>cross-references from one TModule to another TModule.</p>
</li>
<li>
<p><code>astElement</code> links from TModule to AST whenever the AST is not present (e.g. resource was loaded from Xtext index).</p>
</li>
<li>
<p><code>definedType</code> links from AST to TModule after deleting the TModule (this happens in the incremental builder after the pre-linking phase).</p>
</li>
<li>
<p>all kinds of links after demand-loading an AST by resolving an <code>astElement</code> link (pathological case).</p>
</li>
</ul>
</div>
</li>
<li>
<p>resolution is handled in two ways:</p>
<div class="ulist">
<ul>
<li>
<p>if the context <code>EObject</code> of the proxy, i.e. the one where the proxified cross-reference originates, is contained in an N4JSResource <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math>, then resolution is handled by <code>N4JSResource#doResolveProxy()</code> (see also <code>ProxyResolvingResource</code> for details).</p>
<div class="paragraph">
<p>In this case, special handling is performed to make sure that (a) the target resource is loaded from the index, if possible, and (b) post-processing of the target resource is initiated iff the target resource was loaded from AST (instead from the Xtext index) AND post-processing of resource <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math> is currently in progress or has already been completed.</p>
</div>
</li>
<li>
<p>otherwise, resolution is handled by standard EMF functionality.</p>
</li>
</ul>
</div>
</li>
<li>
<p>latest time of resolution: none. In fact, some of those proxies (those representing <code>astElement</code> links from TModule to AST) must not be resolved at all, because this is not yet properly handled.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_how-is-proxy-resolution-triggered"><a class="anchor" href="#_how-is-proxy-resolution-triggered"></a><a class="link" href="#_how-is-proxy-resolution-triggered">9.11.3. How is Proxy Resolution Triggered?</a></h4>
<div class="paragraph">
<p>Resolution of proxies throughout the N4JS implementation is triggered as usually when using EMF, which means: whenever the getter of a EMF cross-reference is invoked and the value is still a proxy, the EMF-generated code of the getter will automatically trigger resolution of this proxy. For details look at the EMF-generated code of the getter of any cross-reference (<code>IdentifierRefImpl#getId()</code> would be a good example).</p>
</div>
</div>
<div class="sect3">
<h4 id="_when-is-proxy-resolution-allowed"><a class="anchor" href="#_when-is-proxy-resolution-allowed"></a><a class="link" href="#_when-is-proxy-resolution-allowed">9.11.4. When is Proxy Resolution Allowed?</a></h4>
<div class="paragraph">
<p>So, at what time is it legal to trigger such a proxy resolution? Or, more concretely, during which resource load states (<a href="type_index.html#sec:N4JS_Resource_Load_States">N4JS Resource Load States</a>) is it legal to trigger proxy resolution? In fact, asking the question in this way is incorrect or at least not very helpful, because the answer would be (almost) always. The better question is: which components of the system / which parts of the code base are allowed to trigger proxy resolution?</p>
</div>
<div class="paragraph">
<p>For example, triggering resolution is disallowed in the <code>ASTStructureValidator</code> and <code>N4JSTypesBuilder</code>, but for the outside client code such as a JUnit test it is allowed to trigger proxy resolution as early as right after parsing. For an example of the latter see test <code>#testStateFullyProcessed_triggeredOnlyThroughProxyResolution()</code> in <code>N4JSResourceLoadStatesTest</code>.</p>
</div>
<div class="paragraph">
<p>In summary, we can state the rule that the <strong>internal N4JS implementation</strong> must not trigger any proxy resolution until installation of the derived state has completed, i.e. not before resource load state "Fully Initialized", but <strong>client code</strong> may trigger proxy resolution as early as right after parsing, i.e. already in resource load state "Loaded".</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.9<br>
Last updated 2019-08-08 13:15:33 CEST
</div>
</div>
<!-- ************* docinfo-footer *************************************************************** -->
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<!-- ************* UI Scripts ************* -->
<script type="text/javascript" src="scripts/back-to-top.js"></script>

<script type="text/javascript" src="scripts/treeview.js"></script>
<script type="text/javascript" src="scripts/toc.js"></script>

<!-- ************* Prism.js Syntax Highlighting ************* -->
<script src="scripts/prism.js"></script>

<script type="text/javascript">
	// Add the 'toclist' id for search function
	$(".toc2 > ul").attr('id', 'toclist');
	// Generate a Search input form
	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
	$("#clear").click(function(){
	    $("#pagesearch").val('');
	    search();
	    $('.toc2 > ul').treeView('collapseAll');
	});
	// intialize Treeview.js
	$(".toc2 > ul").treeView();
	// Initialize Scrollspy
</script>
<!-- ************* docinfo-footer *************************************************************** -->
</body>
</html>